Skip to content

docs: document the composition catalog and release 2.1.0 - #5

Merged
ruehowl merged 2 commits into
mainfrom
claude/stacks-docs-release-n0tygw
Jul 27, 2026
Merged

ruehowl merged 2 commits into
mainfrom
claude/stacks-docs-release-n0tygw

Conversation

@ruehowl

@ruehowl ruehowl commented Jul 27, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

Documentation for the stack, plus two fixes found while writing and verifying it, plus the version bump to publish it.

New docs

File Covers
README.md (new) What the repo is, the nine-composition catalog with a "which variant do I want" guide, the trigger → environment → profile → capability pipeline, the CI plan/run matrix, consuming the published OCI package, and the release process
stacks/stack-tectonic-flare/README.md (new) Anatomy of a composition (composition.yaml / schema.yaml / jobs / profiles and what each answers), the shared profile lanes, the two layers of deploy gating, the template context, and conventions for adding a composition

Rewritten composition READMEs (all 9)

The previous READMEs were scaffolding that described files this repo does not contain — compositions.yaml (the file is composition.yaml), examples/<fixture>, tests/smoke, and ./scripts/verify-composition.sh — while documenting no steps, profiles, inputs, or credentials. publish-stack additionally listed registry and version as required inputs; they are optional in the schema and are not read by the job template at all.

Each README now documents:

  • the contract — type, schema name, job, default profile, runner, timeout, scope label
  • a step × profile matrix: every step in template order, its capability, what it actually runs, and a tick per profile that selects it
  • every schema input, required vs optional, with what reads it (including the inputs that are declared but unused, marked as such)
  • deploy/apply gating — the Environment + productionBranch conditions, the three-way branch in the Worker deploy steps, and which credentials are asserted on which path
  • the Terraform variable contract for the two Terraform-backed Pages compositions
  • a component.yaml usage example

Fix: terraform verify profile planned an apply

profiles/terraform-verify.yaml, described as "Full non-mutating verification", listed terraform.apply in includeCapabilities — so the verify lane planned terraform apply -auto-approve.

Verified with a throwaway terraform component and orun plan:

before: setup-terraform, Terraform Context, fmt Check, Init, Validate, Plan, Apply
after:  setup-terraform, Terraform Context, fmt Check, Init, Validate, Plan

terraform.apply is removed from the verify profile, and is now declared in the job template's capabilities block alongside the step that already used it (confirmed inert — the profile filter is what selects steps). No shipped profile selects it, which matches the composition's own framing: release is "release-grade validation before apply-capable workflows". This is called out in the terraform README under a "Changed in 2.1.0" note. No component in this repo uses the terraform composition, so nothing here changes behaviour today.

Fix: CI was red before this branch, from CLI drift

The first push of this branch failed the stack-tectonic · dev · Publish check before any step ran:

✕ remote state auth (oidc exchange): OIDC exchange returned status 403

sourceplane/orun-action defaults to version: latest. The last green run (16 May) resolved v1.26.0 — the version kiox.lock pins. Today latest resolves v2.38.0, whose remote-state OIDC exchange the backend rejects. Same workflow, same secrets, same repo; only the installed CLI changed.

Both action invocations in .github/workflows/verify.yml are now pinned to v1.26.0, and CI is green again. This is unrelated to the docs work — it is what unblocks merging.

Note the composition's own setup-orun step (inside the publish-stack job template) still installs latest and resolved v2.38.0 in the green run; orun publish works fine on it. Only the outer runner needed pinning.

Release

stack.yaml metadata.version → 2.1.0 (minor: new docs, one profile capability removed from a lane that should never have had it). Merging this publishes ghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0 via the stack-tectonic · staging · Publish check.

Verification

Locally:

$ orun compositions list          # 9 compositions resolve
$ orun plan --intent intent.yaml  # 1 component × 3 envs → 3 jobs
$ cd stacks/stack-tectonic-flare && orun publish --dry-run
  → would push to ghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0

In CI (both checks green on 819f39a), the dry-run lane confirms the release target:

✓  02 publish-dry-run   package  tectonic-flare
                        version  2.1.0
                        registry ghcr.io/sourceplane/saas-stack-tectonic-flare
   ✓ dry run: no files uploaded
   → would push to ghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0

Every YAML file parses, and all relative links in the new and rewritten markdown resolve to real paths.

Regenerated .orun/component-tree.yaml and .orun/compositions.lock.yaml were deliberately left out of the commits — the local CLI is a different version from the one that generated them and rewrites unrelated fields.

claude added 2 commits July 27, 2026 12:56
Adds a repository README and a stack README, and rewrites all nine
composition READMEs as consumer-facing contracts.

The previous composition READMEs pointed at files that do not exist in
this repo (compositions.yaml, examples/, tests/smoke,
scripts/verify-composition.sh) and documented no steps, profiles, inputs,
or credentials. Each one now covers:

- the composition contract (type, schema, job, default profile, runner)
- a step x profile matrix, so it is clear which capabilities each lane
  selects and which steps are dropped from the plan
- every schema input with required/optional status and what reads it
- deploy and apply gating, plus the credentials each gated path asserts
- a component.yaml usage example

Repo README covers the trigger -> environment -> profile -> capability
pipeline, the CI plan/run matrix, consuming the published package, and
the release process. Stack README covers the composition anatomy, the
profile lanes, the two layers of deploy gating, and the conventions for
adding a composition.

Also fixes the terraform composition: the verify profile, described as
"full non-mutating verification", included terraform.apply and therefore
planned `terraform apply -auto-approve`. Confirmed with a probe component
that the Apply step was planned before the change and is not after it.
terraform.apply is now declared on the job template alongside the step
that uses it, and is selected by no shipped profile.

Bumps the stack to 2.1.0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013saWA8jdvjSTjhWGFefzMg
The orun-action defaults to `version: latest`. In May it resolved
v1.26.0, matching the provider pinned in kiox.lock, and the publish job
passed. It now resolves v2.38.0, and every job fails before running a
step with:

  ✕ remote state auth (oidc exchange): OIDC exchange returned status 403

Same workflow, same secrets, same repo — only the installed CLI changed.
Pinning both action invocations to v1.26.0 puts CI back on the version
this workspace declares.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013saWA8jdvjSTjhWGFefzMg
@ruehowl
ruehowl marked this pull request as ready for review July 27, 2026 13:01
@ruehowl
ruehowl merged commit d2a5219 into main Jul 27, 2026
2 checks passed
@ruehowl
ruehowl deleted the claude/stacks-docs-release-n0tygw branch July 27, 2026 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants